﻿namespace Lite.Common
{
    /// <summary>
    /// A generic interface for types that can be started and halted.
    /// </summary>
    /// <remarks>
    /// A class that implements this interface should be capable of moving
    /// from a started state to a stopped state and back an indefinite number
    /// of times. Halting is not equivalent to Disposing - the instance is
    /// still accessible and potentially restartable.
    /// </remarks>
    public interface IStartHalt
    {
        /// <summary>
        /// Gets the current state of the instance.
        /// </summary>
        StartHaltState State { get; }

        /// <summary>
        /// Attempt to move the instance into the Started state.
        /// </summary>
        /// <remarks>
        /// If the instance is in the Started or Paused states, this will have
        /// no effect; otherwise, it will move into the Started state.
        /// </remarks>
        void Start();

        /// <summary>
        /// Attempt to move the instance into the Halted state.
        /// </summary>
        /// <remarks>
        /// <para>
        /// If the instance is in the Halting or Halted states, this will
        /// have no effect; otherwise, it will move into the Halting state
        /// until it has finished any pending work, at which point it will move
        /// into the Halted state.
        /// </para>
        /// <para>
        /// I wanted to called this Stop, but apparently that's a reserved word.
        /// Bloody VB. *humph*
        /// </para>
        /// </remarks>
        void Halt();
    }
}
